Monitoring and Maintenance

**Referenced Files in This Document** - [cloudflare-pages.toml](file://cloudflare-pages.toml) - [netlify.toml](file://netlify.toml) - [worker.js](file://worker.js) - [wrangler.jsonc](file://wrangler.jsonc) - [package.json](file://package.json) - [.eleventy.js](file://.eleventy.js) - [src/feed.njk](file://src/feed.njk) - [src/sitemap.njk](file://src/sitemap.njk) - [src/_data/site.json](file://src/_data/site.json) - [src/admin/config.yml](file://src/admin/config.yml) - [tina/config.ts](file://tina/config.ts)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document provides comprehensive guidance for monitoring, maintenance, and operational procedures for the platform. It covers performance monitoring strategies (Cloudflare observability, custom metrics, and error tracking), maintenance procedures (content updates, security patches, dependency updates), logging and debugging approaches for both frontend and backend, RSS feed generation and syndication, backup and recovery procedures, practical examples of monitoring dashboards and alerting, incident response, security maintenance (SSL, vulnerability scanning, access control), capacity planning and scaling, and administrative procedures for content moderation and system health checks.

Project Structure

The platform is a static site generated by Eleventy and deployed via Cloudflare Workers for dynamic routes and asset hosting. The Cloudflare Worker handles member authentication, OAuth for the CMS, and a live polling API. Netlify and Cloudflare Pages configurations are present for historical or alternative deployments. The CMS is powered by TinaCMS with a GitHub backend.

graph TB
Dev["Developer Workflow<br/>Eleventy Build"] --> Eleventy[".eleventy.js<br/>Collections, Filters, Transforms"]
Eleventy --> Site["_site output"]
Site --> CFWorker["Cloudflare Worker<br/>worker.js"]
CFWorker --> KV["KV Namespaces<br/>MEMBER_EMAILS, MAGIC_TOKENS"]
CFWorker --> Resend["Email Delivery<br/>Resend API"]
CFWorker --> GH["GitHub OAuth<br/>Sveltia CMS"]
CFWorker --> Sheets["Google Sheets API<br/>Live Polling"]
CFWorker --> Assets["Static Assets<br/>ASSETS binding"]
CFWorker --> Browser["Browser Requests"]
Browser --> CFWorker

Diagram sources

  • [worker.js:1-321](file://worker.js#L1-L321)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)
  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)

Section sources

  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)
  • [netlify.toml:1-26](file://netlify.toml#L1-L26)
  • [worker.js:1-321](file://worker.js#L1-L321)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)
  • [package.json:1-32](file://package.json#L1-L32)
  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)

Core Components

  • Static site generation and build pipeline orchestrated by Eleventy with RSS feed and sitemap generation.
  • Cloudflare Worker for dynamic routes: member authentication, magic-link login, logout, OAuth handshake, and live polling API.
  • CMS via TinaCMS with GitHub backend for content editing and media management.
  • Deployment configuration for Cloudflare Workers and legacy Pages/Netlify configurations.

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [worker.js:1-321](file://worker.js#L1-L321)
  • [src/feed.njk:1-27](file://src/feed.njk#L1-L27)
  • [src/sitemap.njk:1-16](file://src/sitemap.njk#L1-L16)
  • [src/admin/config.yml:1-774](file://src/admin/config.yml#L1-L774)
  • [tina/config.ts:1-331](file://tina/config.ts#L1-L331)

Architecture Overview

The runtime architecture combines static generation with serverless edge logic. The Cloudflare Worker intercepts member-protected routes and API endpoints, while the rest of the traffic serves static assets. Observability is enabled in the Worker configuration.

sequenceDiagram
participant U as "User"
participant W as "Cloudflare Worker"
participant K as "KV Namespaces"
participant R as "Resend API"
participant G as "GitHub OAuth"
participant S as "Google Sheets API"
U->>W : Request /alliance/members/*
W->>W : Read session cookie
W->>W : Verify session token
alt Valid session
W-->>U : Serve protected page (ASSETS)
else No session
W-->>U : Redirect to /alliance/login?next=...
end
U->>W : POST /alliance/login (magic link)
W->>K : Lookup approved email
alt Approved
W->>R : Send magic link email
else Not approved
W->>R : Optionally send generic message
end
W-->>U : Redirect to /alliance/login?sent=1
U->>W : GET /alliance/verify?token=...
W->>K : Retrieve token and delete
W-->>U : Set session cookie and redirect to members portal
U->>W : GET /api/auth (start OAuth)
W-->>U : Redirect to GitHub authorize
U->>W : GET /api/auth/callback
W->>G : Exchange code for access token
W-->>U : Return token to opener (CMS)
U->>W : GET /api/polling.json
W->>S : Fetch polling data
W-->>U : JSON response with cache headers

Diagram sources

  • [worker.js:77-321](file://worker.js#L77-L321)
  • [wrangler.jsonc:6-8](file://wrangler.jsonc#L6-L8)

Detailed Component Analysis

Cloudflare Worker: Dynamic Routes and APIs

  • Member authentication:
    • Session cookie handling with secure, HttpOnly, SameSite, and Max-Age attributes.
    • HMAC-signed session tokens with expiry validation and constant-time signature verification.
    • Magic-link issuance with one-time tokens stored in KV with TTL.
  • OAuth for CMS:
    • Authorization code flow with GitHub, returning tokens to the opener window.
  • Live polling API:
    • Fetches data from Google Sheets, returns structured JSON with cache-control headers.
  • Observability:
    • Observability enabled in Wrangler configuration.

Operational notes:

  • Secrets and KV namespaces are configured via Wrangler; ensure bindings and secrets are provisioned.
  • Error responses return structured JSON for API routes; consider adding structured error logs for diagnostics.

Section sources

  • [worker.js:12-321](file://worker.js#L12-L321)
  • [wrangler.jsonc:6-8](file://wrangler.jsonc#L6-L8)

Eleventy Build Pipeline and Content Collections

  • Passthrough copies for assets, admin, and redirects.
  • Watch targets for CSS, JS, and data directories.
  • Custom filters and transforms for content processing and HTML minification in production.
  • RSS feed and sitemap generation via dedicated templates.

Operational notes:

  • Production builds enable HTML minification; ensure local development mirrors production behavior for performance testing.
  • RSS and sitemap templates rely on Eleventy collections; verify collection names and data availability.

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [src/feed.njk:1-27](file://src/feed.njk#L1-L27)
  • [src/sitemap.njk:1-16](file://src/sitemap.njk#L1-L16)

CMS Configuration (TinaCMS + GitHub Backend)

  • TinaCMS defines collections for content types and data files.
  • GitHub backend configuration specifies repository and branch.
  • Media handling configured to upload images under a specific directory.

Operational notes:

  • Ensure GitHub tokens and permissions are correctly configured for the CMS to write content.
  • Keep TinaCMS schema aligned with Eleventy data files to avoid rendering errors.

Section sources

  • [src/admin/config.yml:1-774](file://src/admin/config.yml#L1-L774)
  • [tina/config.ts:1-331](file://tina/config.ts#L1-L331)

Deployment and Environment Configurations

  • Cloudflare Pages configuration is deprecated; canonical deployment is via Cloudflare Workers.
  • Netlify configuration sets security headers and caching for assets.
  • Wrangler enables observability and binds static assets.

Operational notes:

  • Use Wrangler for deploying and managing the Worker and assets.
  • Review headers and redirects for security posture and compatibility.

Section sources

  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)
  • [netlify.toml:14-26](file://netlify.toml#L14-L26)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)

Dependency Analysis

The system’s runtime dependencies include:

  • Cloudflare Worker runtime and KV namespaces for authentication and session tokens.
  • External APIs for email delivery, GitHub OAuth, and Google Sheets.
  • Build-time dependencies for Eleventy, RSS plugin, and search indexing.
graph LR
Eleventy["Eleventy Build"] --> Site["_site"]
Site --> Worker["Cloudflare Worker"]
Worker --> KV["KV Namespaces"]
Worker --> Resend["Resend API"]
Worker --> GitHub["GitHub OAuth"]
Worker --> Sheets["Google Sheets API"]
Worker --> Assets["Static Assets"]

Diagram sources

  • [worker.js:1-321](file://worker.js#L1-L321)
  • [wrangler.jsonc:9-12](file://wrangler.jsonc#L9-L12)

Section sources

  • [worker.js:1-321](file://worker.js#L1-L321)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)

Performance Considerations

  • Static asset delivery:
    • Leverage CDN caching and immutable caching for assets as configured in Netlify.
  • Edge compute:
    • Use Cloudflare Worker for low-latency authentication and API responses.
  • Build optimization:
    • Enable HTML minification in production builds.
    • Consider image optimization and compression for media assets.
  • API caching:
    • Apply appropriate cache-control headers for polling API responses.
  • Observability:
    • Enable and monitor Worker metrics and logs for latency and error rates.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Member authentication failures:
    • Verify KV namespaces are bound and secrets are set.
    • Confirm session cookie attributes and SameSite/Lax compatibility.
  • OAuth handshake errors:
    • Check GitHub client credentials and callback URL alignment.
  • Polling API errors:
    • Validate Google Sheets ID and API key configuration.
    • Inspect network and rate limits for external APIs.
  • Build and deployment:
    • Ensure Node version and build scripts match environment expectations.
    • Confirm Wrangler configuration and asset binding.

Section sources

  • [worker.js:70-76](file://worker.js#L70-L76)
  • [worker.js:233-276](file://worker.js#L233-L276)
  • [wrangler.jsonc:28-34](file://wrangler.jsonc#L28-L34)
  • [package.json:5-12](file://package.json#L5-L12)

Conclusion

The platform leverages a static-first approach with Cloudflare Workers for dynamic functionality, ensuring scalability and performance. Robust monitoring, maintenance, and operational procedures are essential for reliability. The guidance provided here offers practical steps for observability, security, content management, and incident response.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Monitoring Dashboards and Alerting Examples

  • Dashboards:
    • Cloudflare Workers dashboard: track requests, errors, execution duration, and bandwidth.
    • Netlify/Cloudflare Pages analytics: monitor traffic and performance metrics.
  • Alerting:
    • Set alerts for elevated error rates, timeouts, and KV unavailability.
    • Monitor OAuth and email delivery success rates.
  • Metrics:
    • Track API response times for polling endpoint.
    • Observe KV lookup and token creation latencies.

[No sources needed since this section provides general guidance]

Backup and Recovery Procedures

  • Content:
    • Back up Eleventy content and data files regularly; maintain versioned snapshots.
    • Preserve TinaCMS configuration and GitHub repository history.
  • Secrets and KV:
    • Document and securely back up Wrangler secrets and KV namespace IDs.
    • Maintain a recovery plan for KV data restoration.
  • Assets:
    • Store static assets in version control or a secure offsite location.
  • Testing:
    • Periodically test restore procedures for content and configuration.

[No sources needed since this section provides general guidance]

Security Maintenance

  • SSL/TLS:
    • Ensure domain certificates are valid and renewed automatically via Cloudflare.
  • Vulnerability scanning:
    • Scan dependencies periodically and update packages according to a patch schedule.
  • Access control:
    • Restrict CMS access to authorized users; review GitHub repository permissions.
    • Audit KV namespace access and secrets rotation.

[No sources needed since this section provides general guidance]

Capacity Planning and Scaling

  • Traffic spikes:
    • Scale horizontally with Cloudflare Workers; monitor cold start and concurrency limits.
  • Storage:
    • Optimize asset sizes and leverage CDN caching to reduce origin load.
  • APIs:
    • Rate-limit and cache external API calls; consider quotas and fallbacks.

[No sources needed since this section provides general guidance]

Administrative Procedures

  • Content moderation:
    • Establish editorial workflows; review drafts and published content regularly.
  • User access management:
    • Manage CMS users and permissions; rotate tokens and secrets.
  • System health checks:
    • Monitor Worker uptime, KV availability, and external API health.
    • Validate RSS and sitemap integrity after content updates.

[No sources needed since this section provides general guidance]